Inside Macintosh: Open Transport /

Chapter 2 - Providers / Providers Reference

Functions / Installing and Removing a Notifier Function

OTInstallNotifier

Installs a notifier function.

C INTERFACE

OSStatus OTInstallNotifier (ProviderRef ref, OTNotifyProcPtr proc, 
                            void* contextPtr);

C++ INTERFACE

OSStatus TProvider::InstallNotifier (OTNotifyProcPtr proc, 
                                     void* contextPtr);

PARAMETERS

ref

The provider reference of the provider for which you are installing a notifier.

proc

A pointer to a notifier function that you provide.

For C++ applications, the proc parameter must point to either a C function or a static member function.

contextPtr

A context pointer for your use. The provider passes this value unchanged to your notifier function when it calls the function.

DESCRIPTION

The OTInstallNotifier function installs a notifier function for the provider that you specify. Changing a provider's mode of execution does not affect the notifier function. The notifier function remains installed until you remove it using the OTRemoveNotifier function or until you close the provider.

Before calling the OTInstallNotifier function, you must open the provider for which you want to install the notifier. If you open a provider asynchronously (for example, with the OTAsyncOpenEndpoint function), you must pass a pointer to a notifier function as a parameter to the function used to open the provider. In this case, you don't need to call the OTInstallNotifier function unless you want to install a different notifier function. If you do, you must call the OTRemoveNotifier function before calling the OTInstallNotifier function.

Opening a provider synchronously (for example, with the OTOpenEndpoint function) opens the provider but does not install a notifier function for it. If you need a notifier function for a provider opened synchronously, you must call the OTInstallNotifier function. This notifier would not return completion events, but would return asynchronous events advising you of the arrival of data, of changes in flow-control restrictions, and so on.

Call the OTInstallNotifier function only when no provider functions are executing for the provider that you specify. Otherwise, the OTInstallNotifier function returns the result code kOTStateChangeErr.

If you try to install a notifier function for a provider that already has a notifier, the function returns with the kOTAccessErr result.

IMPORTANT

On 68000-based Macintosh computers, the OTInstallNotifier function saves the current value of the A5 register. Open Transport restores the A5 register to this saved value when calling the notifier function you install. If your environment stores context information in a register other than A5, your notifier function must save and restore the value of that register.

SEE ALSO

Notifier functions are described in "Application-Defined Functions" (page 2-44).

To remove an installed notifier function, call the OTRemoveNotifier function, described in the next section.